<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xml:lang="fr" xmlns="http://www.w3.org/1999/xhtml">
	<head>
		<title>Cosmoscroll - Guide du développeur</title>
		<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
		<style type="text/css">
body {
	font-family: arial, serif;
	font-size: 11pt;
	margin: 0;
	padding: 2em;
}
h1 {
	color: #36383D;
}
h2 {
	background-color: #36383D;
	color: white;
	padding: 2px;
	text-indent: 1em;
}
h3 {
	text-decoration: underline;
}
div.part {
	padding: 0 2em;
}
code, pre {
	background-color: #FFF0C0;
}
pre {
	border: 1px solid #FFD0A0;
	padding: 0.5em;
}
pre .color-string {
	color: #0000FF;
}
table.infotab {
	border-collapse: collapse;
}
table.infotab td, table.infotab th {
	border: 1px solid black;
	padding: 0.3em;
}
table.infotab th {
	background-color: silver;
}
		</style>
	</head>
	<body>

	<h1>Cosmoscroll - Guide du développeur</h1>

	<h2>Introduction</h2>
	<div class="part">
	<p>
		Ce document est destiné aux personnes souhaitant partiticper au développement de CosmoScroll, « <em>Le Défilement Cosmique</em> ».
		<br />Sommaire :
	</p>
	<ul>
		<li><a href="#src">Organisation des sources</a></li>
		<li><a href="#coding-style">Style de codage</a></li>
		<li><a href="#xml-levels">Niveaux</a></li>
		<li><a href="#xml-ships">Vaisseaux</a></li>
		<li><a href="#xml-animations">Animations</a></li>
		<li><a href="#xml-weapons">Armes</a></li>
		<li><a href="#config">Fichier de configuration</a></li>
		<li><a href="#i18n">Internationalisation</a></li>
	</ul>
	</div>

	<h2 id="scr">Organisation des sources</h2>
	<div class="part">
	<h3>Organisation générale</h3>
	<ul>
		<li>
			<b>bin</b><br />
			Contient l'exécutable, les DLL et tous les fichiers ressources du jeu.<br />
			Seul le contenu du dossier bin est redistribué, le reste n'est pas nécessaire au joueur.
			<ul>
				<li>
					<b>config</b><br />
					Les fichiers de configuration du jeu sauvegardés automatiquement (le jeu peut fonctionner sans en utilisant sa configuration par défaut).
				</li>
				<li>
					<b>screenshot</b><br />
					Les captures d'écran prises par le joueur.
				</li>
				<li>
					<b>data</b><br />
					Les ressources nécessaires au fonctionnement du jeu.
					<ul>
						<li><b>font</b></li>
						<li><b>images</b></li>
						<li><b>lang</b>: fichiers de traduction</li>
						<li><b>levels</b>: niveaux du mode histoire, au format XML (<a href="#xml-levels">détails ici</a>)</li>
						<li><b>music</b></li>
						<li><b>sound</b></li>
						<li><b>xml</b>: définitions des données du jeu en XML (armes, vaisseaux, etc.)</li>
					</ul>
				</li>
			</ul>
		</li>
		<li>
			<b>doc</b><br />
			Éléments de documentation.
		</li>
		<li>
			<b>src</b><br />
			Les fichiers sources (détails plus bas)
			<ul>
				<li><b>core</b></li>
				<li><b>entities</b></li>
				<li><b>scenes</b></li>
				<li><b>tinyxml</b></li>
				<li><b>utils</b></li>
			</ul>
		</li>
		<li>
			<b>src-images</b><br />
			Certaines ressources graphiques dans leur format natif (fichiers GIMP, etc.) pour les éditer plus facilement (avant de les convertir en png ou jpg dans bin/data/images).
		</li>
	</ul>
	<p>Détail des sous-dossiers src : </p>

	<h3>core</h3>
	<p>Contient le point d'entrée du programme (<code>Main.cpp</code>) et les classes directement liées à la gestion du jeu. L'application est pilotée par la classe singleton <code>Game</code>, qui se charge d'initialiser le jeu, d'afficher les scènes, et de sauvegarder la configuration en quittant.</p>

	<h3>entities</h3>
	<p>Les entités sont les éléments graphiques qui interragissent avec le joueur durant les phases de jeu, le vaisseau du joueur étant lui-même une entité.</p>
	<p>Toutes les entités héritent de la classe abstraite <code>Entity</code> et sont gérées par le singleton <code>EntityManager</code>. EntityManager se charge ainsi de :</p>
	<ul>
		<li>Charger les définitions des entités depuis des fichiers XML</li>
		<li>Allouer les entités sur demande</li>
		<li>Mettre à jour, déplacer, afficher les entités</li>
		<li>Gérer les collisions et autres événements</li>
	</ul>
	<p>Les classes suivantes héritent de Entity et représentent des entités concrètes :</p>
	<table class="infotab">
		<tr>
			<th>Classe</th>
			<th>Rôle</th>
		</tr>
		<tr>
			<td>Asteroid</td>
			<td>astéroïde qui peut se divisier en plusieurs astéroïdes plus petits</td>
		</tr>
		<tr>
			<td>Hit</td>
			<td>Projectile tiré par une arme</td>
		</tr>
		<tr>
			<td>ImpactHit</td>
			<td>hérite de Hit, projectile spécial avec dégât de zone tiré par MissileLauncher</td>
		</tr>
		<tr>
			<td>SpaceShip</td>
			<td>un vaisseau, chargé depuis un profil XML</td>
		</tr>
		<tr>
			<td>PlayerShip</td>
			<td>le vaisseau du joueur, réagit aux événements</td>
		</tr>
		<tr>
			<td>EvilBoss</td>
			<td>super boss de fin très méchant</td>
		</tr>
	</table>
	<p>Les autres classes, Weapon et MissileLauncher, sont des attributs des entités et servent à émettre des Hit et des ImpactHit</p>

	<h3>scenes</h3>
	<p>Les scènes sont la base de tout écran visuel, et héritent toutes de la classe abstraite BaseScene.<br />
	Les scènes (que l'on peut décrire comme "un écran du jeu") sont gérées par la classe Game qui se charge de les allouer, les afficher (BaseScene::Show), les mettre à jour (BaseScene::Update) et leur envoyer les événements reçus (BaseScene::OnEvent).</p>
	<p>Toutes les scènes qui sont des menus héritent de BaseMenu (BaseMenu héritant de BaseScene)</p>

	<h3>utils</h3>
	<p>Ce module regroupe des classes et des fonctions utilitaires, tout ces éléments sont des outils indépendants du jeu (aucun élément d'utils doit inclure des éléments des autres modules).<br />
	On y trouve :</p>
	<ul>
		<li>StringUtils : fonctions qui complètent les méthodes de std::string</li>
		<li>Math : fonctions de géométrie 2D</li>
		<li>ConfigParser : manipuler des fichiers de config avec une syntaxe proche de CSS</li>
		<li>MediaManager : classe singleton pour charger et stocker les fichiers média (images, sons, etc.)</li>
		<li>DIE : macro pour tuer le jeu, avec un message d'erreur indiquant la ligne et le nom du fichier où l'appel a eu lieu</li>
		<li>DumbMusic : classe pour jouer simplement des musiques avec la libdumb (la classe Music de la SFML ne gère pas le format .mod)</li>
	</ul>

	<h3>tinyxml</h3>
	<p>Contient les sources de la bibliothèque TinyXML. Inclure simplement tinyxml/tinyxml.h pour l'utiliser</p>
	</div>

	<h2 id="coding-style">Style de codage</h2>
	<div class="part">
	<ul>
		<li>Fichiers sources encodés en UTF-8</li>
		<li>Code en anglais, documentation en français ou en anglais</li>
		<li>Pas de variables globales</li>
		<li>L'accolade ouvrante se place sur une nouvelle ligne</li>
		<li>L'indentation utilise le caractère tabulation</li>
		<li>Les noms des classes et des méthodes sont écrite en <em>CamelCase</em><br />
<pre>
class MyClass
{
public:
	void GetSometing() const;

	void SetSometing(int value);
};
</pre>
		</li>
		<li>Les constantes sont en majuscules (ex : MA_CONSTANTE), les variables en minuscules (ex : ma_variable)</li>
		<li>Les attributs des classes sont suivis d'un underscore :<br />
<pre>
class MyClass
{
private:
	int var_;
};
</pre>
		</li>
		<li>Les fichiers .hpp et .cpp prennent le nom de la classe qu'ils définissent (Java-like)</li>
		<li>Cartouches Doxygen dans les headers</li>
	</ul>
	</div>

	<h2 id="xml-levels">Niveaux</h2>
	<p>Les niveaux sont scriptés en XML et sont stockés dans le fichier <code>bin/data/levels/levels.xml</code></p>
	<p>Le fichier se divise en deux éléments principaux :</p>
	<ul>
		<li><b>functions</b> : des procédures stockées qui peuvent être appelées comme une fonction en programmation</li>
		<li><b>levels</b> : la liste des niveaux</li>
	</ul>
	<h3>Fonctions</h3>
	<p>Chaque fonction est défini par un tag <b>def</b> et un attribut <b>name</b> unique</p>
	<p>Le scritage du corps d'une fonction obéit aux mêmes règles que le scriptage des niveaux.</p>

	<h3>Niveaux</h3>
	<p>Chaque niveau est identifié par un tag <b>level</b>.<br />
	<em>Attributs :</em></p>
	<ul>
		<li><b>desc</b> : nom ou texte de description du niveau</li>
		<li><b>bg_top</b> (optionnel) : couleur de fond du haut de l'écran au format HTML, noir si non indiqué</li>
		<li><b>bg_bottom</b> (optionnel) : couleur de fond du bas de l'écran au format HTML, noir si non indiqué</li>
		<li><b>starts</b> : nombre d'étoiles défilantes dans l'arrière plan</li>
	</ul>
	<p>La liste des tags constituant le corps d'un niveau (ou d'une fonction') est indiquée ci-dessous.</p>

	<h3>Tags de déclaration d'entités</h3>
	<ul>
		<li>
			<b>ship</b> : instance de SpaceShip<br />
			<em>attributs :</em>
			<ul>
				<li><b>id</b> : id du type de vaisseau (voir <a href="#xml-ships">définition des vaisseaux</a>)</li>
			</ul>
		</li>
		<li><b>asteroid</b> : instance de Asteroid</li>
		<li><b>evilboss</b> : instance de EvilBoss</li>
		<em>attributs communs à tous les tags entités :</em>
		<ul>
			<li><b>x</b> : position x (obligatoire)</li>
			<li><b>y</b> : position y (défault : bord droit de l'écran)</li>
			<li><b>t</b> : temps d'apparition en seconde, relatif au t de l'entité précédente (défaut : 0)</li>
		</ul>
	</ul>
	<h3>Autres tags</h3>
	<ul>
		<li>
			<b>loop</b> : permet de boucler sur les tags enfants contenus<br />
			<em>attributs :</em>
			<ul>
				<li><b>count</b> : nombre de passage dans la boucle</li>
			</ul>
			Accepte tous les tags enfants (ship, asteroid, evilboss, loop, call, wait).
		</li>
		<li>
			<b>call</b> : appeler une fonction<br />
			<em>attributs :</em>
			<ul>
				<li><b>func</b> : nom de la fonction à appeler</li>
			</ul>
		</li>
		<li>
			<b>wait</b> : temps d'attente avant la prochaine instruction<br />
			<em>attributs :</em>
			<ul>
				<li><b>t</b> : temps d'attente avant la prochaine instruction, exprimé en seconde</li>
			</ul>
		</li>
	</ul>
	<p>Ces tags permettent une meilleure factorisation du code XML des niveaux, des fonctions peuvent appeler d'autres fonctions, des boucles peuvent être imbriquées dans d'autres boucles, etc.</p>

	<h2 id="xml-ships">Vaisseaux</h2>
	<div class="part">
	<p>Les différents types de vaisseaux (tous instances de la classe <b>SpaceShip</b>) sont définis en XML dans le fichier <code>bin/data/xml/spaceships.xml</code>.</p>

<pre>﻿&lt;?xml version=<span class="color-string">"1.0"</span> encoding=<span class="color-string">"utf-8"</span> ?&gt;
&lt;spaceships&gt;
	&lt;ship id=<span class="color-string">"1"</span> name=<span class="color-string">"Capsule"</span> animation=<span class="color-string">"capsule"</span> hp=<span class="color-string">"3"</span> speed=<span class="color-string">"75"</span> move=<span class="color-string">"STRAIGHT"</span>&gt;
	&lt;/ship&gt;
	&lt;ship id=<span class="color-string">"2"</span> name=<span class="color-string">"Scoot"</span> animation=<span class="color-string">"scoot"</span> hp=<span class="color-string">"4"</span> speed=<span class="color-string">"200"</span> move=<span class="color-string">"STRAIGHT"</span> attack=<span class="color-string">"ON_SIGHT"</span>&gt;
		&lt;weapon id=<span class="color-string">"0"</span> x=<span class="color-string">"0"</span> y=<span class="color-string">"16"</span> /&gt;
	&lt;/ship&gt;
	&lt;ship id=<span class="color-string">"3"</span> name=<span class="color-string">"Interceptor"</span> animation=<span class="color-string">"interceptor"</span> hp=<span class="color-string">"8"</span> speed=<span class="color-string">"25"</span> move=<span class="color-string">"MAGNET"</span> attack=<span class="color-string">"AUTO_AIM"</span>&gt;
		&lt;weapon id=<span class="color-string">"0"</span> x=<span class="color-string">"0"</span> y=<span class="color-string">"32"</span> /&gt;
	&lt;/ship&gt;
	&lt;ship id=<span class="color-string">"4"</span> name=<span class="color-string">"UFO"</span> animation=<span class="color-string">"ufo"</span> hp=<span class="color-string">"6"</span> speed=<span class="color-string">"80"</span> move=<span class="color-string">"STRAIGHT"</span> attack=<span class="color-string">"AUTO_AIM"</span>&gt;
		&lt;weapon id=<span class="color-string">"4"</span> x=<span class="color-string">"0"</span> y=<span class="color-string">"24"</span> /&gt;
	&lt;/ship&gt;
&lt;/spaceships&gt;
</pre>

	<ul>
		<li>
			<b>ship</b><br />
			<em>attributs :</em>
			<ul>
				<li><b>id</b> : identifiant numérique unique</li>
				<li><b>animation</b> : nom de l'animation associée (voir la <a href="#xml-animations">définition des animations</a>)
				<li><b>name</b> : nom du vaisseau</li>
				<li><b>hp</b> : nombre de points de vie</li>
				<li><b>speed</b> : vitesse de déplacement, exprimée en pixels/seconde</li>
				<li><b>move</b> : comportement de déplacement, cet attribut peut prendre les valeurs suivantes :<br />
					<ul>
						<li><b>straight</b> : le vaisseau avance toujours tout droit (valeur par défaut)</li>
						<li><b>magnet</b> : le vaisseau suit le joueur</li>
						<li><b>sinus</b> : le vaisseau avance sur une courbe sinusoïdale</li>
					</ul>
				</li>
				<li><b>attack</b> : comportement d'attaque, cet attribut peut prendre les valeurs suivantes :<br />
					<ul>
						<li><b>none</b> : le vaisseau n'attaque jamais (valeur par défaut)</li>
						<li><b>on_sight</b> : le vaisseau tire si le joueur passe devant lui</li>
						<li><b>auto_aim</b> : le vaisseau tire sur le joueur en continue, en calculant le bon angle de tir</li>
					</ul>
				</li>
			</ul>
			<em>tags enfants :</em>
			<ul>
				<li>
					<b>weapon</b><br />
					attributs
					<ul>
						<li><b>id</b> : id de l'arme (voir <a href="#xml-weapons">définition des armes</a>)</li>
						<li><b>y</b> : position x de l'arme, par rapport au coin supérieur gauche du vaisseau</li>
						<li><b>x</b> : position y de l'arme, par rapport au coin supérieur gauche du vaisseau</li>
					</ul>
				</li>
			</ul>
		</li>
	</ul>
	</div>

	<h2 id="xml-animations">Animations</h2>
	<div class="part">
	<p>Les animations servent à définir un cycle d'images pour représenter un objet animé. Elles sont notamment utilisées sur les objets <b>SpaceShip</b><br />
	Chaque animation est associée à une image qui regroupe les différentes frames de l'animation, les frames doivent être de dimensions identiques et positionnées selon une séquence horizontale sur l'image.</p>
<p><em>Schéma d'une image d'une animation de 3 frames :</em></p>
<pre>
+---------+---------+---------+
|         |         |         |
| Frame 1 | Frame 2 | Frame 3 |
|         |         |         |
+---------+---------+---------+
</pre>
<p><em>Exemple XML :</em></p>

<pre>﻿&lt;?xml version=<span class="color-string">"1.0"</span> encoding=<span class="color-string">"utf-8"</span> ?&gt;
&lt;animations&gt;
	&lt;anim name=<span class="color-string">"capsule"</span>        img=<span class="color-string">"ship-capsule"</span>     width=<span class="color-string">"32"</span> height=<span class="color-string">"32"</span> count=<span class="color-string">"8"</span>  delay=<span class="color-string">"0.1"</span> /&gt;
	&lt;anim name=<span class="color-string">"scoot"</span>          img=<span class="color-string">"ship-scoot"</span>       width=<span class="color-string">"48"</span> height=<span class="color-string">"32"</span> count=<span class="color-string">"2"</span>  delay=<span class="color-string">"0.1"</span> /&gt;
	&lt;anim name=<span class="color-string">"interceptor"</span>    img=<span class="color-string">"ship-interceptor"</span> width=<span class="color-string">"56"</span> height=<span class="color-string">"48"</span> count=<span class="color-string">"2"</span>  delay=<span class="color-string">"0.1"</span> /&gt;
	&lt;anim name=<span class="color-string">"playership-red"</span> img=<span class="color-string">"playership"</span>       width=<span class="color-string">"64"</span> height=<span class="color-string">"40"</span> count=<span class="color-string">"2"</span>  delay=<span class="color-string">"0.1"</span> /&gt;
	&lt;anim name=<span class="color-string">"ufo"</span>            img=<span class="color-string">"ship-ufo"</span>         width=<span class="color-string">"48"</span> height=<span class="color-string">"48"</span> count=<span class="color-string">"3"</span>  delay=<span class="color-string">"0.1"</span> /&gt;
	&lt;anim name=<span class="color-string">"explosion"</span>      img=<span class="color-string">"explosion"</span>        width=<span class="color-string">"64"</span> height=<span class="color-string">"64"</span> count=<span class="color-string">"11"</span> delay=<span class="color-string">"0.12"</span> /&gt;
&lt;/animations&gt;</pre>

	<ul>
		<li><b>animations</b>
			<ul>
				<li><b>name</b> : nom identifiant l'animation</li>
				<li><b>img</b> : chemin de l'image de l'animation (sans l'extension), relatif au dossier data/images</li>
				<li><b>width</b> : largeur d'une frame, en pixels</li>
				<li><b>height</b> : hauteur d'une frame, en pixels</li>
				<li><b>count</b> : nombre de frames qui composent l'animation</li>
				<li><b>delay</b> : délai entre chaque frame, en seconde</li>
			</ul>
		</li>
	</ul>
	</div>

	<h2 id="xml-weapons">Armes</h2>
	<div class="part">
	<p>Les armes et leurs projectiles sont définis en XML dans le fichier <code>bin/data/xml/weapons.xml</code></p>
<pre>﻿&lt;?xml version=<span class="color-string">"1.0"</span> encoding=<span class="color-string">"utf-8"</span> ?&gt;
&lt;weapons&gt;
	&lt;weapon id=<span class="color-string">"plasma"</span>     image=<span class="color-string">"ammo/plasma"</span>      heat_cost=<span class="color-string">"5"</span>   fire_rate=<span class="color-string">"3"</span>   damage=<span class="color-string">"1"</span>  speed=<span class="color-string">"380"</span> /&gt;
	&lt;weapon id=<span class="color-string">"laser-beam"</span> image=<span class="color-string">"ammo/laserbeam"</span>   heat_cost=<span class="color-string">"3"</span>   fire_rate=<span class="color-string">"8"</span>   damage=<span class="color-string">"2"</span>  speed=<span class="color-string">"360"</span> sound=<span class="color-string">"blaster-shot-1"</span> /&gt;
	&lt;weapon id=<span class="color-string">"canon"</span>      image=<span class="color-string">"ammo/hellfire"</span>    heat_cost=<span class="color-string">"1.7"</span> fire_rate=<span class="color-string">"18"</span>  damage=<span class="color-string">"1"</span>  speed=<span class="color-string">"480"</span> sound=<span class="color-string">"blaster-shot-2"</span> /&gt;
	&lt;weapon id=<span class="color-string">"devil-eyes"</span> image=<span class="color-string">"ammo/devil-eyes"</span>  heat_cost=<span class="color-string">"1"</span>   fire_rate=<span class="color-string">"0.7"</span> damage=<span class="color-string">"6"</span>  speed=<span class="color-string">"430"</span> /&gt;
&lt;/weapons&gt;
</pre>


	<ul>
		<li>
			<b>weapon</b><br />
			<em>attributs :</em>
			<ul>
				<li><b>id</b> : identifiant numérique unique</li>
				<li><b>name</b> : nom de l'arme</li>
				<li><b>image</b> : chemin de l'image du projectile tiré (sans l'extension), relatif au dossier data/images</li>
				<li><b>heat_cost</b> : quantité de chaleur dégagée par coup</li>
				<li><b>fire_rate</b> : cadence de tir, exprimée en nombre de coups par seconde</li>
				<li><b>damage</b> : dégâts par projectile</li>
				<li><b>speed</b> : vitesse des projectiles, exprimée en pixels/seconde</li>
				<li><b>sound</b> (optionnel) : chemin du son joué à chaque tir (sans l'extension), relatif au dossier data/sound</li>
			</ul>
		</li>
	</ul>
	</div>

	<h2 id="config">Fichier de configuration</h2>
	<div class="part">
	<p>Les préférences du joueur et ses scores sont stockés dans le fichier de configuration (<code>config/config.cfg</code>).<br />
	Ce fichier n'est pas nécessaire au fonctionnement du jeu et sera créé automatiquement lors de la première utilisation
	</p>
	<p>Le fichier est structuré en différentes sections :</p>
	<ul>
		<li>Joystick<br />Les bindings des actions pour le joystick (numéros des boutons)</li>
		<li>Keyboard<br />Les bindings des actions pour le clavier (code SFML des touches du clavier)</li>
		<li>Settings
			<ul>
				<li>arcade_high_score : meilleur score en mode Arcade</li>
				<li>current_level : niveau sélectionné par défaut</li>
				<li>enable_music :</li>
				<li>fullscreen : 0 = mode fenêtré, 1 = mode plein écran (défaut : 0)</li>
				<li>last_unlocked_level : dernier niveau débloqué</li>
				<li>music_name : nom de la musique choisie</li>
				<li>panel_on_top : 0 = panel en bas, 1 = panel en haut (défaut : 1)</li>
			</ul>
		</li>
		<li>Audio
			<ul>
				<li>enable_music: activer la musique (0|1)</li>
				<li>enable_sound: activer les sons (0|1)</li>
				<li>music_name: nom de la musique jouée</li>
				<li>music_volume: volume de la musique (0-100)</li>
				<li>sound_volume: volume des sons (0-100)</li>
			</ul>
		</li>
		<li>Story
			<ul>
				<li>current_level: niveau courant</li>
				<li>last_unlocked_level: dernier niveau débloqué</li>
			</ul>
		</li>
	</ul>
	</div>

	<h2 id="i18n">Internationalisation</h2>
	<div class="part">
	<p>L'internationalisation est prise en charge avec les fichiers de langue situés dans <code>data/lang/</code>. Le jeu détecte automatiquement la locale du système et tente de charger le fichier de langue correspondant à <code>data/lang/&lt;les deux premières lettres de la locale en minuscules&gt;.lang</code>. Si ce fichier est introuvable, <code>en.lang</code> (english) sera utilisé par défaut.</p>
	<p>Les fichier .lang <b>doivent</b> être encodés en UTF-8, et contiennent un élément de traduction par ligne, la syntaxe est <code>clef = chaîne traduite</code>.<br />Exemple :</p>
	<pre>
# Ceci est un commentaire

menu.play = Jouer
menu.quit = Quitter
</pre>

	</div>
	</body>
</html>
